Inside Macintosh: QuickTime

Previous | Chapter Top | Chapter Contents | Next

NewMovieFromFile

The NewMovieFromFile function creates a movie in memory from a resource that is stored in a movie file. Your application specifies the movie file with the file reference number that was returned by the OpenMovieFile function, which is described on OpenMovieFile . Your application can use the NewMovieFromHandle function, described in the next section, to load a movie from a handle. Once you have opened a movie file and loaded a movie, your application can proceed to work with the movie.

pascal OSErr NewMovieFromFile (Movie *theMovie, short resRefNum,
                                         short *resId,
                                         StringPtr resName,
                                         short newMovieFlags,
                                         Boolean *dataRefWasChanged);


theMovie

Contains a pointer to a field that is to receive the new movie's identifier. If the function cannot load the movie, the returned identifier is set to nil .

resRefNum

Identifies the movie file from which the movie is to be loaded. Your application obtains this value from the OpenMovieFile function, described on OpenMovieFile .

resId

Contains a pointer to a field that specifies the resource containing the movie data that is to be loaded. If the field referred to by the resId parameter is set to 0, the Movie Toolbox loads the first movie resource it finds in the specified file. The toolbox then returns the movie's resource ID number in the field referred to by the resId parameter. The following enumerated constant is available:

movieInDataForkResID

Forces the movie to come out of the data fork. If the resource was stored in the file's data fork, the Movie Toolbox sets the returned value to movieInDataForkResID (-1). In this case, you cannot add a movie resource to the file unless you create a resource fork in the movie file.

If the resId parameter is set to nil , the Movie Toolbox loads the first movie resource it finds in the specified file and does not return that resource's ID number.

resName

Points to a character string that is to receive the name of the movie resource that is loaded. If you set the resName parameter to nil , the toolbox does not return the resource name.

newMovieFlags

Controls the operation of the NewMovieFromFile function. The following flags are available (be sure to set unused flags to 0):

newMovieActive

Controls whether the new movie is active. Set this flag to 1 to make the new movie active. You can make a movie active or inactive by calling the SetMovieActive function, which is described on SetMovieActive .

newMovieDontResolveDataRefs

Controls how completely the Movie Toolbox resolves data references in the movie resource. If you set this flag to 0, the toolbox tries to completely resolve all data references in the resource. This may involve searching for files on multiple volumes. If you set this flag to 1, the Movie Toolbox only looks in the specified file.

If the Movie Toolbox cannot completely resolve all the data references, it still returns a valid movie identifier. In this case, the Movie Toolbox also sets the current error value to couldNotResolveDataRef .

newMovieDontAskUnresolvedDataRefs

Controls whether the Movie Toolbox asks the user to locate files. If you set this flag to 0, the Movie Toolbox asks the user to locate files that it cannot find. If the Movie Toolbox cannot locate a file even with the user's help, the function returns a valid movie identifier and sets the current error value to couldNotResolveDataRef .

newMovieDontAutoAlternate

Controls whether the Movie Toolbox automatically selects enabled tracks from alternate track groups. If you set this flag to 1, the Movie Toolbox does not automatically select tracks for the movie--you must enable tracks yourself.

dataRefWasChanged

Contains a pointer to a Boolean value. The Movie Toolbox sets the Boolean to indicate whether it had to change any data references while resolving them. The toolbox sets the Boolean value to true if any references were changed. Use the UpdateMovieResource function (described on UpdateMovieResource ) to preserve these changes.

Set the dataRefWasChanged parameter to nil if you do not want to receive this information. See "Creating Tracks and Media Structures," for more information about data references.

NewMovieFromHandle

The NewMovieFromHandle function creates a movie in memory from a movie resource or a handle you obtained from the PutMovieIntoHandle function.

pascal OSErr NewMovieFromHandle (Movie *theMovie, Handle h,
                                         short newMovieFlags,
                                         Boolean *dataRefWasChanged);


theMovie

Contains a pointer to a field that is to receive the new movie's identifier. If the function cannot load the movie, the returned identifier is set to nil .

h

Contains a handle to the movie resource from which the movie is to be loaded.

newMovieFlags

Controls the operation of the NewMovieFromHandle function. The following flags are available (be sure to set unused flags to 0):

newMovieActive

Controls whether the new movie is active. Set this flag to 1 to make the new movie active. You can make a movie active or inactive by calling the SetMovieActive function, which is described on SetMovieActive .

newMovieDontResolveDataRefs

Controls how completely the Movie Toolbox resolves data references in the movie resource. If you set this flag to 0, the toolbox tries to completely resolve all data references in the resource. This may involve searching for files on remote volumes. If you set this flag to 1, the Movie Toolbox only looks in the specified file.

If the Movie Toolbox cannot completely resolve all the data references, it still returns a valid movie identifier. In this case, the Movie Toolbox also sets the current error value to couldNotResolveDataRef .

newMovieDontAskUnresolvedDataRefs

Controls whether the Movie Toolbox asks the user to locate files. If you set this flag to 0, the Movie Toolbox asks the user to locate files that it cannot find on available volumes. If the Movie Toolbox cannot locate a file even with the user's help, the function returns a valid movie identifier and sets the current error value to couldNotResolveDataRef .

newMovieDontAutoAlternate

Controls whether the Movie Toolbox automatically selects enabled tracks from alternate track groups. If you set this flag to 1, the Movie Toolbox does not automatically select tracks for the movie--you must enable tracks yourself.

dataRefWasChanged

Contains a pointer to a Boolean value. The Movie Toolbox sets the Boolean value to indicate whether it had to change any data references in order to resolve them. The toolbox sets the Boolean value to true if any references were changed. Set the dataRefWasChanged parameter to nil if you do not want to receive this information.

NewMovie

The NewMovie function creates a new movie in memory. The Movie Toolbox initializes the data structures for the new movie, which contains no tracks. Your application assigns the data to the movie by calling the functions that are described later in "Creating Tracks and Media Structures," .

pascal Movie NewMovie (long flags);


flags

Specifies control information for the new movie. The following flags are available (be sure to set unused flags to 0):

newMovieActive

Controls whether the new movie is active. Set this flag to 1 to make the new movie active. A movie that does not have any tracks can still be active. When the Movie Toolbox tries to play the movie, no images are displayed, because there is no movie data. You can make a movie active or inactive by calling the SetMovieActive function, which is described on SetMovieActive .

newMovieDontAutoAlternate

Controls whether the Movie Toolbox automatically selects enabled tracks from alternate track groups. If you set this flag to 1, the Movie Toolbox does not automatically select tracks for the movie--you must enable tracks yourself.

ConvertFileToMovieFile

The ConvertFileToMovieFile takes a specified file and converts it to a movie file.

pascal OSErr ConvertFileToMovieFile (const FSSpec *inputFile,
                                          const FSSpec *outputFile,
                                          OSType creator,
                                          ScriptCode scriptTag,
                                          short *resID, long flags,
                                          ComponentInstance userComp,
                                          MovieProgressUPP proc,
                                          long refCon);


inputFile

Contains a pointer to the file system specification for the file to be converted into a movie file.

outputFile

Contains a pointer to the file specification for the destination movie file.

creator

Specifies the creator value for the file if it is a new one.

scriptTag

Specifies the script in which the movie file should be converted. Use the Script Manager constant smSystemScript to use the system script; use the smCurrentScript constant to use the current script. See Inside Macintosh: Text for more information about scripts and script tags.

resID

Contains a pointer to a field that is to receive the resource ID of the file to be converted. If you don't want to receive the resource ID, set this parameter to nil .

flags

Controls movie file conversion flags. The following value is valid:

createMovieFileDeleteCurFile

Indicates whether to delete an existing file. If you set this flag to 1, the Movie Toolbox deletes the file (if it exists) before converting the new movie file. If you set this flag to 0 and the file specified by the fileSpec parameter already exists, the Movie Toolbox uses the existing file. In this case, the toolbox ensures that the file has both a data and a resource fork.

userComp

Indicates a component or component instance of the movie export component you want to perform the conversion. Otherwise, set this parameter to 0 for the Movie Toolbox to choose the appropriate component. If you pass in a component instance, it will be used by ConvertFileToMovieFile . This allows you to communicate directly with the component before using this function to establish any conversion parameters. If you pass in a component ID, an instance is created and closed within this function. For details on movie export components, see Inside Macintosh: QuickTime Components .

proc

Points to your progress function. To remove a movie's progress function, set this parameter to nil . Set this parameter to -1 for the Movie Toolbox to provide a default progress function. See "Progress Functions," which begins on Progress Functions , for the interface your progress function must support.

refCon

Specifies a reference constant. The Movie Toolbox passes this value to your progress function.

ConvertMovieToFile

The ConvertMovieToFile function takes a specified movie (or a single track within that movie) and converts it into a specified file and type.

pascal OSErr ConvertMovieToFile(Movie theMovie, Track onlyTrack,
                                          FSSpec *outputFile,
                                          OSType fileType, OSType creator,
                                          ScriptCode scriptTag,
                                          short *resID, long flags,
                                          ComponentInstance userComp);


theMovie

Specifies the source movie for this conversion operation. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , and NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).

onlyTrack

Specifies the track within the source movie for this conversion operation. To specify all tracks, set the value of this parameter to 0.

outputFile

Contains a pointer to the file specification for the destination file.

fileType

Specifies the data type of the destination file for the movie specified in the parameter theMovie .

creator

Specifies the creator value for the output file if it is a new one.

scriptTag

Specifies the script into which the movie should be converted if the output file is a new one. Use the Script Manager constant smSystemScript to use the system script; use the smCurrentScript constant to use the current script. See Inside Macintosh: Text for more information about scripts and script tags.

resID

Contains a pointer to a field that is to receive the resource ID of the open movie. If you don't want to receive this information, set the resID parameter to nil .

flags

Set this parameter to 0.

userComp

If you want a particular movie export component to perform the conversion, you may pass the component or an instance of that component in this parameter. Otherwise, set it to 0 to allow the Movie Toolbox to use the appropriate component. If you pass in a component instance, it is used by ConvertMovieToFile . This allows you to communicate directly with the component before making this call to establish any conversion parameters. If you pass in a component ID, an instance is created and closed within this call.

DisposeMovie

The DisposeMovie function frees any memory being used by a movie, including the memory used by the movie's tracks and media structures. Your application should call this function when it is done working with a movie.

pascal void DisposeMovie (Movie theMovie);


theMovie

Identifies the movie to be freed. Your application obtains this movie identifier from such functions as NewMovie , NewMovieFromFile , or NewMovieFromHandle (described on NewMovie , NewMovieFromFile , and NewMovieFromHandle , respectively).

CreateMovieFile

The CreateMovieFile function creates an open movie file, opens the movie file, creates an empty movie which references the file, and opens the movie file with write permission.

pascal OSErr CreateMovieFile (const FSSpec *fileSpec,
                                         OSType creator,
                                         ScriptCode scriptTag,
                                         long createMovieFileFlags,
                                         short *resRefNum,
                                         Movie *newMovie);


fileSpec

Contains a pointer to the file system specification for the movie file to be created.

creator

Specifies the creator value for the new file.

scriptTag

Specifies the script in which the movie file should be created. Use the Script Manager constant smSystemScript to use the system script; use the smCurrentScript constant to use the current script. See Inside Macintosh: Text for more information about scripts and script tags.

createMovieFileFlags

Controls movie-file creation flags. The following flags are available:

createMovieFileDeleteCurFile

Indicates whether to delete an existing file. If you set this flag to 1, the Movie Toolbox deletes the file (if it exists) before creating the new movie file. If you set this flag to 0 and the file specified by the fileSpec parameter already exists, the Movie Toolbox uses the existing file. In this case, the toolbox ensures that the file has both a data and a resource fork.

createMovieFileDontCreateMovie

Controls whether the CreateMovieFile function creates a new movie in the movie file. If you set this flag to 1, the Movie Toolbox does not create a movie in the new movie file. In this case, the function ignores the newMovie parameter. If you set this flag to 0, the Movie Toolbox creates a movie and returns the movie identifier in the field referred to by the newMovie parameter.

createMovieFileDontOpenFile

Controls whether the CreateMovieFile function opens the new movie file. If you set this flag to 1, the Movie Toolbox does not open the new movie file. In this case, the function ignores the resRefNum parameter. If you set this flag to 0, the Movie Toolbox opens the new movie file and returns its reference number into the field referred to by the resRefNum parameter.

newMovieActive

Controls whether the new movie is active. Set this flag to 1 to make the new movie active. A movie that does not have any tracks can still be active. When the Movie Toolbox tries to play the movie, no images are displayed, because there is no movie data. You can make a movie active or inactive by calling the SetMovieActive function, which is described on SetMovieActive .

newMovieDontAutoAlternate

Controls whether the Movie Toolbox automatically selects enabled tracks from alternate track groups. If you set this flag to 1, the Movie Toolbox does not automatically select tracks for the movie--you must enable tracks yourself.

resRefNum

Contains a pointer to a field that is to receive the file reference number for the opened movie file. Your application must use this value when calling other Movie Toolbox functions that work with movie files. If you set this parameter to nil , the Movie Toolbox creates the movie file but does not open the file.

newMovie

Contains a pointer to a field that is to receive the identifier of the new movie. The CreateMovieFile function returns the identifier of the new movie. If the function could not create a new movie, it sets this returned value to nil . If you set this parameter to nil , the Movie Toolbox does not create a movie.

OpenMovieFile

The OpenMovieFile function opens a specified movie file. Your application identifies the movie file with a file system specification.

pascal OSErr OpenMovieFile (const FSSpec *fileSpec,
                                          short *resRefNum, SInt8 permission);


fileSpec

Contains a pointer to the file system specification for the movie file to be opened.

resRefNum

Contains a pointer to a field that is to receive the file reference number for the opened movie file. Your application must use this value when calling other Movie Toolbox functions that work with movie files. This reference number refers to the file fork that contains the movie resource--if the movie is stored in the data fork of the file, the returned reference number corresponds to the data fork.

permission

Specifies the permission level for the file. If your application is only going to play the movie that is stored in the file, you can open the file with read permission. If you plan to add data to the file or change data in the file, you should open the file with write permission. Supply a valid File Manager permission value. See Inside Macintosh: Files for valid values.

CloseMovieFile

The CloseMovieFile function closes an open movie file.

pascal OSErr CloseMovieFile (short resRefNum);


resRefNum

Specifies the movie file to close. Your application obtains this reference number from the OpenMovieFile function, which is described in the previous section.

DeleteMovieFile

The DeleteMovieFile function deletes a movie file.

pascal OSErr DeleteMovieFile (const FSSpec *fileSpec);


fileSpec

Contains a pointer to the file system specification for the movie file to be deleted.